.\" $Id: PAPI_write.3,v 1.7 2004/10/04 02:16:27 jthomas Exp $
.TH PAPI_write 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
.nf
PAPI_write \- Write counter values into counters
.fi

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int PAPI_write(int " EventSet ", long_long *" values ");"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_write(C_INT\  EventSet,\  C_LONG_LONG(*)\  values,\  C_INT\  check )
.fi

.SH DESCRIPTION
.B "PAPI_write()"
writes the counter values provided in the array 
.I values
into the event set
.I EventSet.
The virtual counters managed by the PAPI library will be set to the 
values provided. If the event set is running, an attempt will be made 
to write the values to the running counters. This operation is
not permitted by all substrates and may result in a run-time error.

.SH ARGUMENTS
.I "EventSet"
--  an integer handle for a PAPI event set as created by
.BR "PAPI_create_eventset" (3)
.LP
.I *values
-- an array to hold the counter values of the counting events

.SH RETURN VALUES
On success, this function returns
.B "PAPI_OK."
 On error, a non-zero error code is returned.

.SH ERRORS
.TP
.B "PAPI_ENOEVST"
The EventSet specified does not exist.
.TP
.B "PAPI_ESBSTR"
PAPI_write() is not implemented for this architecture.
.B "PAPI_ESYS"
The EventSet is currently counting events and the substrate could
not change the values of the running counters.

.SH EXAMPLES
.nf
.if t .ft CW

/* Yet to be written */

.if t .ft P
.fi

.SH BUGS
This function has no known bugs.

.SH SEE ALSO
.BR PAPI_read "(3), " PAPI "(3), " PAPIF "(3), "
